今天來說說串接綠界「全方位金流」最容易遇到的錯誤訊息
CheckMacValue Error

首先，先來說說什麼是CheckMacValue?

假設，你呼叫「全方位金流」API的參數有10組

"TradeDesc" => "促銷方案",
"PaymentType" => "aio",
"MerchantTradeDate" => "2023/03/12 15:30:23",
"MerchantTradeNo" => "ecpay20230312153023",
"MerchantID" => "3002607",
"ReturnURL" => "https://www.ecpay.com.tw/receive.php",
"ItemName" => "Apple iphone 15",
"TotalAmount" => 30000,
"ChoosePayment" => "ALL",
"EncryptType" => 1

那在送出這10組參數前
必須將這10組參數，使用綠界配給你的HashKey、HashIV驗算出CheckMacValue
最後，必須連同原本的參數10組，再加上[CheckMacValue]
6C51C9E6888DE861FD62FB1DD17029FC742634498FD813DC43D4243B5685B840
一共11組參數傳送給綠界

"TradeDesc" => "促銷方案",
"PaymentType" => "aio",
"MerchantTradeDate" => "2023/03/12 15:30:23",
"MerchantTradeNo" => "ecpay20230312153023",
"MerchantID" => "3002607",
"ReturnURL" => "https://www.ecpay.com.tw/receive.php",
"ItemName" => "Apple iphone 15",
"TotalAmount" => 30000,
"ChoosePayment" => "ALL",
"EncryptType" => 1,
"CheckMacValue" => "6C51C9E6888DE861FD62FB1DD17029FC742634498FD813DC43D4243B5685B840"

綠界收到你的請求後，會將請求內的11組參數，移除[CheckMacValue]
再重新使用那10組參數，加上你的HashKey、HashIV驗算[CheckMacValue]

最後綠界驗算的[CheckMacValue]與你自身驗算的[CheckMacValue]必須相同
若綠界算出來的結果，與你算出來的結果不同，綠界就會回傳「CheckMacValue Error」

這裡提供一個簡易驗算[CheckMacValue]的範例:

<?php
	//HashKey
	$hash_key = "pwFHCqoQZGmho4w6";
	//HashIV
	$hash_iv = "EkRm7iFT261dpevs";

	//運算檢查碼的參數
	$form_array = array(
		"TradeDesc" => "促銷方案",
		"PaymentType" => "aio",
		"MerchantTradeDate" => "2023/03/12 15:30:23",
		"MerchantTradeNo" => "ecpay20230312153023",
		"MerchantID" => "3002607",
		"ReturnURL" => "https://www.ecpay.com.tw/receive.php",
		"ItemName" => "Apple iphone 15",
		"TotalAmount" => 30000,
		"ChoosePayment" => "ALL",
		"EncryptType" => 1 
	);

	//特殊字元置換
	function _replaceChar($value)
	{
		$search_list = array('%2d', '%5f', '%2e', '%21', '%2a', '%2A', '%28', '%29');
		$replace_list = array('-', '_', '.', '!', '*' , '*', '(', ')');
		$value = str_replace($search_list, $replace_list ,$value);
		return $value;
	}
	//產生檢查碼
	function _getMacValue($hash_key, $hash_iv, $form_array)
	{
		$encode_str = "HashKey=" . $hash_key;
		foreach ($form_array as $key => $value)
		{
			$encode_str .= "&" . $key . "=" . $value;
		}
		$encode_str .= "&HashIV=" . $hash_iv;
		$encode_str = strtolower(urlencode($encode_str));
		$encode_str = _replaceChar($encode_str);
		//SHA256加密
		return strtoupper(hash('sha256' ,$encode_str));
	}
    //仿自然排序法
    function merchantSort($a,$b)
	{
		return strcasecmp($a, $b);
	}	

	uksort($form_array, 'merchantSort');
	//取得檢查碼
	$form_array['CheckMacValue'] = _getMacValue($hash_key, $hash_iv, $form_array);
	echo $form_array['CheckMacValue'];
?>

以上，就是計算[CheckMacValue]的方式

接下來說一些計算[CheckMacValue]可能會踩的雷:

1. HashKey、HashIV錯誤:

當申請完綠界會員，登入廠商管理後台可以找到自己的HashKey、HashIV

當中可能會有一些容易混淆的字元「l、I、1」等等
如果太相信自己的眼睛，很容易打錯

建議不要鐵齒，乖乖地用「複製、貼上」的方式帶入自己的程式吧
不然很容易發生類似「電腦開不起來，結果是插頭沒插」的低級錯誤喔

還有，有遇過同樣MerchantID的廠商
但金流、物流、電子發票服務的HashKey、HashIV都是不同的

所以千萬不要鐵齒
如果遇到「CheckMacValue Error」還是先去後台看看自己是不是弄錯囉
不然花了一堆時間debug，最後才發現錯在最簡單的地方
那真的是會很生氣呢

2. 空白字元的urlEncode處理

大家的開發環境各不相同
各程式語言在做urlEncode的時候有會有所不同

綠界文件有標示，編碼必須按照.net的編碼原則
如果你的開發環境的編碼與綠界的不同，就必須自行置換
例如使用PHP進行開發，有些符號的urlEncode結果和.net的結果不同，就必須進行置換

以下舉例:
.net會將「空白」變成「+」號
PHP則將「空白」變成「%20」

這類參數通常會出現在「訂單日期」等參數中

"MerchantTradeDate" => "2023/03/12 15:30:23"

所以如果發現你驗算出來的結果與綠界的結果不同
可以看看是不是urlEncode的問題哦

綠界有提供urlEncode轉換表，可以到這裡查看

以上，就是全方位金流的CheckMacValue計算方法
如果有遇到其他問題，歡迎留言分享

我們明天見